Internet Info 1994 March

home *** CD-ROM | disk | FTP | other *** search

/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / networking / terms / kermit / b / ikxker.ins < prev next >

Wrap

Text File | 1993-06-29 | 31.4 KB | 684 lines

IBM System/370 CICS Kermit 4.2.n installation instructions (1993 June) CICS is commonly run under both MVS and VSE, and CICS Kermit may differ slightly between the two systems. Indeed, the installation procedures differ substantially between the two, but the same basic pattern holds. In the following procedure, parallel instructions will be given for both systems wherever the operation differs. There is, as yet, no procedure for installation under VM. Kermit-CICS has been installed and run under versions 1.6, 1.7, 2.1, and 3.1 of CICS; it is not known what changes, if any, are necessary to run it under other versions. * * Installation Procedure * * 1) Allocate disk storage to contain the source and executable code. V S E o n l y The procedure described here assumes that two VSE sublibraries will be used. One sublibrary, called the "base" library, will contain unmodified Kermit source, as received from Columbia. The other sublibrary, called the "work" library, will contain copies of the base library modules to be modified by the LIBR "UPDATE" command. Both libraries may be used for other purposes, since the Kermit maintenance affects only the named modules. It is strongly recommended that the work library be set up for automatic space reuse (the default), as the update process produces interim copies of each module, which are successively replaced. The Kermit update file (IKXKER.UPD) and the VSE update convertor (IKXTRN.ASM) can be stored in either of these libraries or in a third library; or they can be submitted as SYSIPT data from an external system. The Kermit executable phase itself must also, of course, be stored in a library; again, this may be the same as one of the others already discussed. The JCL given below assumes that both IKXTRN.ASM and IKXKER.UPD are stored in VSE libraries. M V S o n l y The allocation sizes here are based on "typical" disk models; each dataset should be roughly 200K in extent. You may wish the primary space parameter to match that size. However, if you wish to reuse either dataset for successive test versions or new releases, you must be sure to make a generous space allocation. Both libraries may be compressed from time to time to make "dead" storage available, but the load library will tend to grow as new releases are added. The load library must be included in the DFHRPL concatenation, since it will contain the Kermit load module. If you have TSO available, it is convenient to use the following commands to allocate the datasets. Note: throughout these instructions, the block size used for objects is 1680, the traditional maximum -- feel free to change it to the customary value at your site. ATTR K1OBJ RECFM(FB) LRECL(80) BLKSIZE(1680) DSORG(PO) ALLOC DSN(KERMIT.CICS.OBJ) USING(K1OBJ) SPACE(20,20) TRACKS DIR(5) ATTR K1LOD RECFM(U) BLKSIZE(6144) DSORG(PO) ALLOC DSN(KERMIT.CICS.LOAD) USING(K1LOD) SPACE(20,20) TRACKS DIR(10) The corresponding JCL is: // EXEC PGM=IEFBR14 //K1OBJ DD DCB=(RECFM=FB,LRECL=80,BLKSIZE=1680,DSORG=PO), // DSN=<user>.KERMIT.CICS.OBJ,SPACE=(TRK,(20,20,5)), // DISP=(NEW,CATLG),UNIT=whatever //K1LOD DD DCB=(RECFM=U,BLKSIZE=6144,DSORG=PO), // DSN=<user>.KERMIT.CICS.LOAD,SPACE=(TRK,(20,20,10)), // DISP=(NEW,CATLG),UNIT=whatever 2) Get the necessary files from the Kermit distribution tape or from BITNET KERMSRV or elsewhere into your disk area. Note that many of the files are generic for Kermit-370 and may already be available to you. As distributed by Columbia, the files are named as follows, almost all with prefix IKX or IK0 (I K Zero). Note that nearly all of these files have records no longer than 80 bytes. The one exception is IKXKER.HLP, which has 96-byte records. IKXKER.BWR A "beware" file, listing known bugs, problems, and fixes IKXKER.DOC CICS Kermit User's Guide, plain text IKXKER.HLP Kermit-CICS online help files IKXKER.INS Kermit-CICS installation instructions (this file) IKXKER.UPD Updates for CICS version of Kermit-370 IKXMAC.ASM Assembler source for CICS-specific macros IKXUTL.ASM Assembler source for CICS-specific routines IK0CMD.ASM Assembler source for command handler IK0COM.ASM Assembler source for global code IK0DEF.ASM Assembler source for parameter definitions IK0DOC.ASM Assembler source with brief history IK0KAN.ASM Assembler source for Kanji character translation IK0MAC.ASM Assembler source for generic Kermit macros IK0MAI.ASM Assembler source for storage initialization IK0PRO.ASM Assembler source for generic routines If you are installing CICS Kermit in CICS/VSE, you will also need the following files. V S E o n l y IKXTRN.ASM Assembler source for the update translation utility If you are installing CICS Kermit in CICS/MVS, you probably already have the materials necessary for installing TSO Kermit on your system. If you do not, you will also need the following files. M V S o n l y IKTDYN.ASM Assembler source for DYNALC subroutine IKTGUP.ASM Assembler source for MVS-specific part of GUPI IKTGUP.HLP GUPI help file, TSO HELP format IKTKER.INS Kermit-TSO installation instructions IKTMAC.ASM Assembler source for TSO-specific macros IK0GUP.ASM Assembler source for generic update program GUPI The following files are not necessary for installation, but may be of some interest. IKCACT.ASM Assembler source for optional accounting exit routine IKXDYN.HLP Specifications for I/O drivers IKXHDR.MSS Scribe source for producing IKXKER.DOC IKXKER.ANN Text of Kermit-CICS announcement for current version IKXKER.LPT Paged equivalent of IKXKER.DOC IKXKER.MSS Scribe source for CICS part of IKXKER.DOC IKXKER.PS PostScript equivalent of IKXKER.DOC IK0AAA.HLP Kermit-370 implementation notes, supported environments IK0CON.HLP Notes on supporting other terminal controllers IK0KER.ANN Text of generic Kermit-370 4.2 announcement IK0KER.MSS Scribe source for generic part of IKXKER.DOC IK0KER.UPD Update history for Kermit-370 IK0POR.HLP Notes on porting Kermit-370 to other systems IK0VER.FOR Comparison program for generating update decks 3) Rename and reformat, if necessary, the source files on disk. Collect all the source files (those with extensions of ".ASM") in your disk area using names as shown above, and make sure that each one has RECFM=FB,LRECL=80, and that all have the same block size. Under VSE, the file extensions for the sources should be changed to ".A". You will also need IKXKER.UPD, and any local updates or optional updates chosen from IKXKER.BWR should also be collected into one or more files for application to the source; the JCL given below (both for VSE and MVS) uses the name IKXKER.LCLUPD as an example for such optional updates. You may have as many separate files of updates as you wish. 4) Define a VSAM KSDS in your CICS to hold Help and TAKE files. It should have the following attributes: DEFINE CLUSTER DATA( KEYS(21 0) RECSZ(80 256) ) DFHFCT TYPE=DATASET,DATASET=KERMFSF,ACCMETH=VSAM, RECFORM=(VARIABLE,BLOCKED),SERVREQ=(READ,ADD,DELETE) Note: in older versions of CICS, the last parameter would be SERVREQ=(GET,NEWREC,DELETE) Copy IKXKER.HLP into KERMFSF using VSAM REPRO so that Kermit-CICS's built-in HELP subcommand can find it. This has the side effect of initializing the KSDS. Special note: with version 4.2.4 of Kermit-CICS, the key size grew from 17 to 21. This requires that the KSDS, if already installed, be recreated when migrating to 4.2.4. If the old KSDS contains any files other than the Help files, they can be backed up and reinserted into the new KSDS by something like the following procedure. a) Copy the entire KSDS to a sequential file using VSAM REPRO. b) Remove all the Help files (all lines with 0000 in columns 1-4 and the word HELP somewhere within columns 5-12). If there are no lines left, the KSDS contained only the original Help files. c) Insert four blanks at column 5 in all the remaining lines of the sequential file, moving everything over to make room, and save the result. d) Merge the saved file with IKXKER.HLP and sort on the key (columns 1-21). Use this sorted file to load the KSDS instead of the "vanilla" IKXKER.HLP. The most comprehensive documentation is the pair of chapters of the Kermit User's Guide dealing with CICS, namely, the generic Kermit-370 chapter and the CICS-specific one. These two are bundled together in IKXKER.DOC and also in IKXKER.PS; the PostScript is suitable only for printing, but the DOC file could also be stored wherever you keep online documentation files, renamed appropriately. 5) The "true" source for Kermit consists of the concatenation of the individual ASM modules plus a number of updates found in IKXKER.UPD. The method of applying these updates depends on the operating system. Also, it depends on the decision of whether to support Japanese Kanji text translation. IK0KAN.ASM is optional. Including it adds about 32 Kbytes to the Kermit program. V S E o n l y The translator program IKXTRN converts the update information in IKXKER.UPD into directives for the library maintenance utility LIBR and submits a batch job to apply the updates. The following JCL assembles, links, and runs IKXTRN for that purpose. In order to avoid making assumptions about the type of scratch disk available, IKXTRN and the JCL are set up to punch a cascading series of jobs into the POWER internal reader, with input data taken from SYSIPT and output written to SYSPCH. You must tailor the job to your site, primarily by filling in the variables denoted in the JCL by lower- case words enclosed in angle brackets "<>". Some of these variables are self-explanatory, but others are described in some detail below. Note: in the following JCL, the normal system libraries are assumed to be universally searchable and are not explicitly mentioned. <sliname> Since some sites may require additional JCL to complete the information normally placed in the standard label area, provision is made for including local JCL via POWER 'SLI' statements at appropriate places in the distributed JCL. If such supplemental JCL is not required, statements with the <sliname> variable may be deleted from the JCL. <class> Replace this variable with the designation of the partition you want each job to run in. <lst specs> Replace this variable with the POWER LST card information needed to route SYSLST output according to local custom. <lib.sublibn> Several versions of this variable occur in the JCL. When "n" has the same value for two different occurrences, both occurrences must identify the same sublibrary. In fact, you may use the same sublibrary for more than one "n"; the only distinction that absolutely must be kept is between n=0 and n=1. The following values of "n" are defined: 0 - The base library for unmodified Kermit Source. 1 - The work library for modified Kermit Source. 2 - The sublibrary where IKXTRN.A is stored. 3 - The sublibrary where IKXUPD.UPD is stored. 4 - The sublibrary where the Kermit phase is to be cataloged. <phasename> Replace this variable with the phase name to be given Kermit, consistent with local CICS naming conventions. KERMIT is a good choice. <v.r> Replace this with the current CICS release number at your site. * $$ JOB JNM=<jobname>,CLASS=<n>,DISP=D * $$ LST <lst specs> * $$ PUN DISP=I,CLASS=<n> // JOB <jobname> SUBMIT KERMIT UPDATES TO IKXTRN PROGRAM * $$ SLI <sliname> // OPTION LINK,NODUMP,DECK // EXEC ASSEMBLY PUNCH '* $$ LST <lst specs>' PUNCH '* $$ PUN DISP=I,CLASS=<n>' PUNCH '// JOB IKXTRN CONVERT KERMIT UPDATES TO VSE LIBR' PUNCH '* $$ SLI <sliname>' PUNCH ' LIBDEF SOURCE,SEARCH=<lib.sublib2>' PUNCH '// OPTION LINK,NODUMP' PUNCH '// EXEC ASSEMBLY,SIZE=256K' PUNCH ' COPY IKXTRN' PUNCH '/*' PUNCH '// EXEC LNKEDT,SIZE=128K' PUNCH '// EXEC ,SIZE=128K' PUNCH 'BASELIBR=<lib.sublib0>' PUNCH 'WORKLIBR=<lib.sublib1>' PUNCH 'LOCALLST=<lst specs>' PUNCH 'LOCALSLI=<sliname>' (optional) PUNCH '00001000=IK0DOC.A' PUNCH '00300000=IK0MAC.A' PUNCH '00800000=IKXMAC.A' PUNCH '01400000=IK0DEF.A' PUNCH '01500000=IK0MAI.A' PUNCH '01800000=IK0COM.A' PUNCH '03000000=IK0CMD.A' PUNCH '05000000=IKXUTL.A' PUNCH '06995000=IK0KAN.A' (optional) PUNCH '07000000=IK0PRO.A' END /* // EXEC LIBR ACCESS SUBLIB=<lib.sublib3> PUNCH IKXKER.UPD FORMAT=NOHEADER EOF=NO PUNCH IKXKER.LCLUPD FORMAT=NOHEADER EOF=NO /* // EXEC ASSEMBLY PUNCH '/*' PUNCH '/&&' PUNCH '* $$ EOJ' END /* /& * $$ EOJ When the foregoing job has completed successfully, the updated Kermit source modules will be found in the <lib.sublib1> sublibrary, where they can be kept either until the installation is complete or until the next installation. To assemble and link Kermit, the following JCL should be run. Tailoring is the same as for the update job, including the possibility of removing IK0KAN if desired. * $$ JOB JNM=<jobname>,CLASS=<n>,DISP=D * $$ LST <lst specs> * $$ PUN DISP=I,CLASS=<n> // JOB LEVEL1 KERMIT TRANSLATE/ASSEMBLE/LINK * $$ SLI <sliname> // OPTION DECK // EXEC ASSEMBLY PUNCH '* $$ LST <lst specs>' PUNCH '* $$ PUN DISP=I,CLASS=<n>' PUNCH '// JOB LEVEL2 KERMIT TRANSLATE/ASSEMBLE/LINK' PUNCH '* $$ SLI <sliname>' PUNCH '// OPTION DECK' PUNCH '// EXEC ASSEMBLY' PUNCH ' PUNCH ''* $$ LST <lst specs>''' PUNCH ' PUNCH ''// JOB LEVEL3 KERMIT TRANSLATE/ASSEMBLE/LINK''' PUNCH ' PUNCH ''* $$ SLI <sliname>''' PUNCH ' PUNCH ''// LIBDEF *,SEARCH=<lib.sublib1>''' PUNCH ' PUNCH ''// OPTION CATAL,SYSPARM=''''<v.r>''''''' PUNCH ' PUNCH '' PHASE <phasename>,*''' PUNCH ' PUNCH '' INCLUDE DFHEAI''' PUNCH ' PUNCH ''// EXEC ASSEMBLY''' PUNCH ' END' PUNCH '/*' PUNCH '// EXEC DFHEAP1$,SIZE=384K' PUNCH '* ASM XOPTS(NOPROLOG,NOEPILOG)' END /* // EXEC LIBR ACCESS SUBLIB=<lib.sublib1> PUNCH IK0DOC.A FORMAT=NOHEADER EOF=NO PUNCH IK0MAC.A FORMAT=NOHEADER EOF=NO PUNCH IKXMAC.A FORMAT=NOHEADER EOF=NO PUNCH IK0DEF.A FORMAT=NOHEADER EOF=NO PUNCH IK0MAI.A FORMAT=NOHEADER EOF=NO PUNCH IK0COM.A FORMAT=NOHEADER EOF=NO PUNCH IK0CMD.A FORMAT=NOHEADER EOF=NO PUNCH IKXUTL.A FORMAT=NOHEADER EOF=NO PUNCH IK0KAN.A FORMAT=NOHEADER EOF=NO PUNCH IK0PRO.A FORMAT=NOHEADER EOF=NO /* // EXEC ASSEMBLY PUNCH '/*' PUNCH '// EXEC ASSEMBLY' PUNCH ' PUNCH ''/*''' PUNCH ' PUNCH ''// LIBDEF *,CATALOG=<lib.sublib4>''' PUNCH ' PUNCH ''// EXEC LNKEDT,SIZE=128K''' PUNCH ' PUNCH ''/*''' PUNCH ' PUNCH ''/&&&&''' PUNCH ' PUNCH ''* $$ EOJ''' PUNCH ' END' PUNCH '/*' PUNCH '/&&' PUNCH '* $$ EOJ' END /* /& * $$ EOJ M V S o n l y The Generic Update Program for IBM-370 (GUPI) handles standard update information in the format found in IKXKER.UPD. Like Kermit itself, GUPI is composed of a generic part and a system-specific part. The former consists of IK0GUP.ASM plus parts of IK0MAC.ASM. There is, however, no CICS version of GUPI, and if your CICS runs under MVS, you must use the MVS (TSO) GUPI. See the instructions in IKTKER.INS for creating MVS GUPI if it has not already been installed in connection with TSO Kermit. The MVS- and TSO-specific parts of GUPI consist of IKTGUP.ASM plus some macros from IKTMAC.ASM. The following batch job uses GUPI to apply the available updates to Kermit and then creates the executable load module KERMIT. Although the job is as generic as possible, there may be local variations. You must tailor the job to your site by (a) supplying an appropriate JOB card (the JOB card should insure, if necessary, a region of at least 2M to allow execution of the assembler and GUPI), (b) changing the string "<user>" into the top-level qualifier of your disk area and "<prefix>" into the top level for CICS, (c) selecting the proper CICS macro library name and inserting the current CICS release number in the definition of proc KXASM, (d) changing the string "<CICSlib>" into the name of the library containing the CICS command-level translator (or removing the STEPLIB from the KXASM.TRN step), (e) changing, if necessary, the name of the assembler, perhaps to IFOX00, and selecting the right DDNAME for the object output, (f) specifying, if necessary, a generous print limit to allow the 13,000 or more lines generated by the job, (g) un-commenting, if desired, the reference to the optional local update data set for input to GUPI (in step KRMUPD) or adding any other desired update data sets to the concatenation under ddname SYSIN, (h) un-commenting, if desired, the references to the optional Kermit accounting exit routine KACCT, (i) commenting out, if desired, the reference to IK0KAN.ASM, (j) selecting a name for the Kermit program and modifying the NAME statement, if necessary, in the last step, and (k) choosing the proper block size for SYSLIN on the KRMLNK step, if necessary, to be as large as that of the Kermit object library. //JOBLIB DD DSN=<user>.KERMIT.LOAD,DISP=SHR //* INPUT: <user>.IK*.ASM, <user>.IKXKER.UPD, <user>.KERMIT.LOAD //* OUTPUT: <user>.KERMIT.CICS.LOAD, <user>.KERMIT.CICS.OBJ //************************ //* Note: CICSREL must be updated appropriately, e.g., 1.7, 2.1, etc //KXASM PROC PRM=,MEMBER=NULL,CICSREL='v.r' //TRN EXEC PGM=DFHEAP1$,REGION=1M,PARM='NOPROLOG,NOEPILOG' //STEPLIB DD DSN=<CICSlib>,DISP=SHR //SYSIN DD DSN=&SOURCE,DISP=(OLD,PASS) //SYSPRINT DD SYSOUT=* //SYSPUNCH DD DSN=&SYSCIN,DISP=(NEW,PASS),UNIT=SYSDA, // SPACE=(TRK,(30,30)),DCB=BLKSIZE=6160 //ASM EXEC PGM=IEV90,REGION=1M, // PARM='RENT,NODECK,OBJECT,SYSPARM(&CICSREL),&PRM' //SYSIN DD DSN=&SYSCIN,DISP=(OLD,DELETE) //SYSLIB DD DSN=<prefix>.CICS.MACLIB,DISP=SHR //SYSLIN DD DSN=<user>.KERMIT.CICS.OBJ(&MEMBER),DISP=(OLD,PASS) //SYSPRINT DD SYSOUT=* //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,2)) // PEND //************************ //KXLINK PROC //LNK EXEC PGM=IEWL,REGION=1M,PARM='REUS,LET' //SYSLIB DD DSN=<prefix>.CICS.LOADLIB,DISP=SHR //SYSLMOD DD DSN=<user>.KERMIT.CICS.LOAD,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(5,2)) // PEND //************************ //* Create updated Kermit ... //KRMUPD EXEC PGM=GUPI,REGION=2M //SYSIN DD DSN=<user>.IKXKER.UPD,DISP=SHR //* DD DSN=<user>.IKXKER.LCLUPD,DISP=SHR Optional //SYSPRINT DD SYSOUT=* //SYSUT1 DD DSN=<user>.IK0DOC.ASM,DISP=SHR // DD DSN=<user>.IK0MAC.ASM,DISP=SHR // DD DSN=<user>.IKXMAC.ASM,DISP=SHR // DD DSN=<user>.IK0DEF.ASM,DISP=SHR // DD DSN=<user>.IK0MAI.ASM,DISP=SHR // DD DSN=<user>.IK0COM.ASM,DISP=SHR // DD DSN=<user>.IK0CMD.ASM,DISP=SHR // DD DSN=<user>.IKXUTL.ASM,DISP=SHR // DD DSN=<user>.IK0KAN.ASM,DISP=SHR (optional) // DD DSN=<user>.IK0PRO.ASM,DISP=SHR //SYSUT2 DD DSN=&&UPDSRC,DISP=(NEW,PASS),SPACE=(CYL,(1,1)), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160),UNIT=SYSDA //* //* KACASM EXEC KXASM,SOURCE='<user>.KACCT.ASM',MEMBER=KACCT //KRMASM EXEC KXASM,SOURCE='&&UPDSRC',MEMBER=KERMIT,COND=(0,LT,KRMUPD) //KRMLNK EXEC KXLINK,COND=((0,LT,KRMUPD),(4,LT,KRMASM.ASM)) //SYSLIN DD DSN=<prefix>.CICS.MACLIB(DFHEILIA),DISP=SHR //* DCB=BLKSIZE=1680 In case BLKSIZE is smaller // DD DSN=<user>.KERMIT.CICS.OBJ(KERMIT),DISP=SHR //* DD DSN=<user>.KERMIT.CICS.OBJ(KACCT),DISP=SHR Optional // DD * NAME KERMIT(R) // Note 1: If you prefer, you may elect to keep the source files in a PDS. If so, be sure to use RECFM=FB,LRECL=80. Also change the DSN references in the preceding job accordingly. Note 2: The procedure given above assumes the availability of sources contemporaneous with this file, i.e., release 4.2 of Kermit-370. Note 3: The procedure given above preserves the sequence numbers in columns 73-80 of the source files. If you elect to use an editor to merge files, be absolutely sure that you don't inadvertently lose the original sequence numbers (something editors are prone to do). 6) You must add Kermit to the PPT and to the PCT to allow Kermit to be run as a transaction under CICS. Here are suggested entries. The program name may be something other than KERMIT, but it must agree with the name used in the installation job above. DFHPPT TYPE=ENTRY,PROGRAM=KERMIT,PGMLANG=ASSEMBLER DFHPCT TYPE=ENTRY,PROGRAM=KERMIT,TRANSID=KERM,DUMP=NO 7) If you plan to have a global Kermit initialization file (common to all users), you must define an extra-partition input TD queue called KSYS to contain the initialization subcommands. The necessary DCT entry should have a definition something like this: DFHDCT TYPE=SDSCI,DSCNAME=KSYSNIT,TYPEFLE=INPUT, RECFORM=VARBLK,RECSIZE=84,BLKSIZE=nnnn DFHDCT TYPE=EXTRA,DESTID=KSYS,DSCNAME=KSYSNIT where "nnnn" is any suitable block size. The DSCNAME value refers to the DOS/VSE DLBL name or the MVS DD name that defines the data set; it may be any suitable value, as long as both DFHDCT entries match. Be sure the data set actually exists, even if it contains no more than a comment line, such as: * CICS Kermit global initialization file. You may add Kermit subcommands to the file as needed. 8) To run Kermit-CICS, simply type "KERMIT" or "KERM" to CICS. Also, Kermit may be executed by other programs non-interactively. * * Data Security * * If you wish to use the optional exits for data security, you must first code the routine(s) according to the needs at your site and then create the object(s) and link explicitly with Kermit. There are three separate exit routines that may be included, all with the same Type-I OS linkage conventions: R13 -> 18-word save area, R14 -> return location, R15 -> called entry point, R1 -> parameter list. In each case, the exit routine is called immediately before Kermit is to perform some possibly forbidden task, and the return code (in R15) tells Kermit whether to proceed. A zero value indicates permission, and any non-zero value forbids the task. If a given routine is not linked with Kermit, the effect is the same as if the return code were always zero. The three exit routines are summarized below. Exit Parameter Explanation ------ ----------- ------------------------------------------------- KVALID FAB FABFNAM has the file name, FABFLGS the type of file, and FABCOMM the operation (See FABD macro). Possible operations are CWD, DELETE, OPEN I, OPEN O, and TEST. KVALID must decide whether the specified access is allowed. Note: the parameter list consists of the FAB itself, rather than a pointer to it. KHIDE ->descriptor TSUTE or DCT or KFSBLK for a queue/file ->FABFLGS flags indicating the type of data object KHIDE must decide whether the name of the object in question may be revealed to the user. This exit routine is invoked during execution of the DIR subcomand with any wildcard specification. A non-zero return code indicates that the very existence of the file is secret. However, if the user supplies the exact name, KHIDE is not called, and DIR will supply the associated information. KHOST ->pgm name 8-byte string (name of program to be invoked) ->command string to be passed to the program in COMMAREA ->length (fullword) length of command string in bytes KHOST must decide whether the named program may be invoked with the given string. * * Userid Routine * * There is a fourth optional exit routine which may be used to set the userid for the purposes of selecting the default directory for I/O to filetype "TAKE". To use this exit routine, you must set the global symbol &USER to the value 'OTHER' in macro SSYMS (see IKXKER.BWR for the update to accomplish that). Exit Parameter Explanation ------ ----------- ------------------------------------------------- KUSER KUSERID KUSERID is a eight-character string to be filled with the default file directory name. KUSER must fill the string (and pad with blanks, if necessary). There is no provision for any error conditions. KUSER will be called only once at the beginning of execution. In addition to the explicit parameter block (the four-byte string), there is an implicit passing of the command-level data storage area via R11. Note: the userid must not begin with either an apostrophe or an asterisk. * * Accounting Routine * * If you wish to use the optional accounting exit routine with Kermit, you must create the object for it and link it explicitly with Kermit. The sample currently available was written for CMS and must be adapted to run under CICS. Any user who does so is urged to contribute the CICS version for inclusion in the Kermit distribution under the name IKXACT.ASM. Even when such a CICS-specific sample is available, you should examine the source and customize it to your installation's needs before using it. The tailored version is assumed to be called KACCT.ASM in the relevant lines of MVS JCL above (currently all commented out). * * Configuration * * The IBM mainframe and its communications front end (3705, 7171, etc.) usually require that parity be used by any asynchronous ASCII device that wishes to communicate with it. Exactly which kind of parity is site-dependent. At Columbia, the 3705 requires Mark parity, and the 7171 requires Even parity. Make sure your users know to use the appropriate parity setting, as well as any other settings required for IBM mainframe communication (see p.36-39 of the Kermit book). For linemode transfers, the ASCII/EBCDIC translation in the front end is a key factor. Kermit-CICS uses an ASCII/EBCDIC translation table which conforms to the one given in the IBM System/370 Reference Summary. If your site's translation table is incompatible with the one Kermit uses, then enter the appropriate SET ATOE/ETOA/TATOE/TETOA subcommands in the system KERMINI file. As long as the system tables are invertible with respect to the printable ASCII characters (even if the A-to-E and E-to-A tables are not the inverses of each other), the SET subcommands can compensate. However, if your system's ASCII/EBCDIC tables are not invertible, Kermit will not and cannot work unless you change your system's tables. Refer to the generic Kermit-370 chapter of the User's Guide for a step-by-step customization procedure (see the section on translation tables). Kermit-CICS operation is possible for many types of protocol converters; it requires only that the converter have some kind of transparent mode. Be sure the converter is configured so that the graphics or transparent mode, whatever it is called, is enabled. See IK0AAA.HLP for a list of front ends that are known to work and for a collection of notes and special warnings about some of them. Some further installation details follow for specific devices. When CICS Kermit is to be used with a 7171, make sure the 7171 is set up with its "keyboard lock delay" parameter set to 0. Otherwise, the "terminal" will hang whenever CICS Kermit clears the screen. This happens consistently when the parameter is set to 10, and not at all when set to 0. For numbers in between, the higher the number, the more it happens. There is another problem in the 7171 that can cause Kermit file transfers to abort after a flurry of retransmissions if XON/XOFF flow control is used by the receiving Kermit, or even by hardware in between the 7171 and the receiver. To prevent this problem, set the 7171 flags so that XOFF is not a valid terminator of a transparent read. See page 4-20 of "IBM 7171 Reference Manual and Programming Guide" (IBM publication number GA27-0021). Kermit operation is possible through an IBM 3708 front end in two different configurations. In the first, the terminal line must be set for either "protocol enveloping" or "dynamic" mode, and a session must be set for line-at-a-time operation for Kermit to work. Other important details of the terminal configuration are: (1) the terminal must be specified as a TWX device, (2) the SSCP format should be set to USSNTO, (3) the terminal type ID should be set to 05, (4) the line should be set for 8, or possibly 7, data bits and 1 stop bit, (5) there should be no "read prompt", and (6) the so-called "alternate" translation table (number 3) should be selected. Kermit-CICS may also need to be configured because some models of the 3708 (or some environments) do not pass the normal packet character SOH (code 1, CTRL-A). A suitable substitute is HT (code 9, CTRL-I). Alternatively, or additionally, it may help to set the 3708 "interface type" to 0. The second possible 3708 configuration is "protocol conversion" mode and makes use of the FULLSCREEN type in Kermit, which is also suitable for many other kinds of protocol converter. The basic setup consists of the following Kermit subcommands. .... mainframe ..... ....... PC ......... SET CONTROLLER FULL set send start 62 SET RECEIVE START 62 set receive start 62 SET SEND START 62 set block b SET BLOCK B set handshake none SET HANDSHAKE 0 The 62's (Greater-than sign) may be replaced by some other decimal code for a printable character. For best results, choose a character that seldom appears in the files you will be transferring. In particular, avoid the Control, Eighth-bit, and Repeat prefixes. Packet sizes are automatically restricted by Kermit-CICS, so you needn't set them unless conditions require packets shorter than the default (77). Flow control may be needed to keep up with the data rate on some equipment. The block check type should be set to "B" only if the protocol converter is overzealous in optimizing the data stream -- there are hazards in using any type other than "1" because of all the packet echoing. Refer to IK0AAA.HLP for such details. Note that the translation of characters imposes the same setup requirements on FULLSCREEN mode as on the traditional TTY mode (linemode). See the DOC. Kermit-CICS supports file transfers through the IBM 3174 AEA with B2 or higher microcode, but support is restricted to terminals with the ASCII Graphics capability in three ways that may require compensating installation: a) The terminal type must be defined in the 3174 to support graphics (only the built-in VT241 and Tektronix 4205 types plus suitable user-defined terminal types). IBM's AEA Reference describes how to set up terminal tables. b) The line must be defined without a Host Addressable Printer. This restriction may not apply if the AEA microcode is at level B4.0 or higher. c) If the 3174 is owned by VTAM, the connection must be made with a logmode that allows the Read Partition Query (such as M2SDLCQ).